RUM-9755: Add Jetpack Compose Instrumentation documentation #29110

ambushwork · 2025-05-02T11:08:32Z

What does this PR do? What is the motivation?

Add documentation page to explain how to instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin.

Merge instructions

Merge readiness:

Release of dd-sdk-android 2.21.0
Release of dd-sdk-android-gradle-plugin 1.17.0

For Datadog employees:
Merge queue is enabled in this repo. Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). Without this format, your pull request will not pass in CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.

If your branch doesn't follow this format, rename it or create a new branch and PR.

To have your PR automatically merged after it receives the required reviews, add the following PR comment:

/merge

Additional notes

github-actions · 2025-05-02T11:11:57Z

Preview links (active after the `build_preview` check completes)

New or renamed files

https://docs-staging.datadoghq.com/ylu/add-compose-instrumentation-doc/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation

Modified Files

https://docs-staging.datadoghq.com/ylu/add-compose-instrumentation-doc/real_user_monitoring/mobile_and_tv_monitoring/android/

aleksandr-gringauz · 2025-05-06T11:45:42Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+As described in the [Setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.
+
+<div class="alert alert-info"><p>
+The Datadog Gradle Plugin scans @Composable functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects NavHost usage and listens to Jetpack Compose navigation events.


You might want to put @Composable and NavHost in quotes so that it is shown as code. You do it in other places.

alert alert-info doesn't support markdown inside, that's why I remove it delibrately.

actually, you could do this:

Suggested change

The Datadog Gradle Plugin scans @Composable functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects NavHost usage and listens to Jetpack Compose navigation events.

The Datadog Gradle Plugin scans <code>@Composable</code> functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects <code>NavHost</code> usage and listens to Jetpack Compose navigation events.

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

maycmlee · 2025-05-06T15:22:39Z

Created docs card for docs review: https://datadoghq.atlassian.net/browse/DOCS-10800

0xnm

lgtm, I left few suggestions

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

plousada · 2025-05-07T12:57:36Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+{{% /tab %}}
+{{< /tabs >}}
+
+### Step 2 - Enable actions tracking option in `RumConfiguration`


I'm slightly confused as to why this is a required step.
What if customer's don't want action tracking and just want view tracking?

More technically speaking, this is a structure limitation of our SDK, we need to make user call this API to let our dd-sdk-android-rum module knows that user has already imported dd-sdk-android-compose module in their app, then dd-sdk-android-rum can use the compose related logic to track actions.

If customer doesn't want Compose action tracking, they can just not call it. should I mention explicitly in this part?

rtrieu

Hi @ambushwork, thank you for this PR! Aside from some of the suggestions I've made, I have a few questions:

would love to know your thoughts on moving this content and putting it as a tab on the Android setup page similar to how we document setup for React Native and related frameworks. I'm not sure how customers think about this framework in particular, how popular it is, and realize it might impact searchability. But at the same time, I'm not sure if it makes sense sitting between Integrated Libraries and Troubleshooting at the moment.
are there any additional steps after instrumentation that we should add, such as re-initializing the application?

Let me know if you have any questions about my feedback and/or submit a re-request for review.

rtrieu · 2025-05-15T18:56:07Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/_index.md

@@ -33,4 +33,5 @@ To get started with RUM for Android, create an application and configure the And
  <u>Integrated Libraries</u>: Import integrated libraries for your Android and Android TV applications.{{< /nextlink >}}
  {{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/troubleshooting">}}
  <u>Troubleshooting</u>: Common troubleshooting Android SDK issues.{{< /nextlink >}}
+  {{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation">}}<u>Jetpack Compose Instrumentation</u>: Instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin. {{< /nextlink >}}


Suggested change

{{< nextlink href="/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation">}}<u>Jetpack Compose Instrumentation</u>: Instrument Jetpack Compose manually or automatically using the Datadog Gradle Plugin. {{< /nextlink >}}

rtrieu · 2025-05-15T18:57:43Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+## Overview
+If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.
+
+<div class="alert alert-info"><p>Note: The minimum supported Kotlin version is 1.9.23.</p></div>


Suggested change

<div class="alert alert-info"><p>Note: The minimum supported Kotlin version is 1.9.23.</p></div>

<div class="alert alert-info"><p>The minimum supported Kotlin version is 1.9.23.</p></div>

removing "note" since it's already in an alert box

rtrieu · 2025-05-15T19:06:18Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+  text: Explore Datadog RUM
+---
+## Overview
+If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.


Suggested change

If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.

Jetpack Compose is a toolkit for building native UI in Android. If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.

rtrieu · 2025-05-15T19:07:19Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+
+## Setup
+### Step 1 - Declare "dd-sdk-android-compose" as a dependency
+Add `dd-sdk-android-compose` dependency to each module you want to instrument. This includes the application module, any Jetpack Compose UI modules, or feature modules using Jetpack Compose.


Suggested change

Add `dd-sdk-android-compose` dependency to each module you want to instrument. This includes the application module, any Jetpack Compose UI modules, or feature modules using Jetpack Compose.

Add `dd-sdk-android-compose` as a dependency to each module you want to instrument. This includes the application module, any Jetpack Compose UI modules, or feature modules using Jetpack Compose.

rtrieu · 2025-05-15T19:36:43Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.
+
+<div class="alert alert-info"><p>Note: The minimum supported Kotlin version is 1.9.23.</p></div>
+


Suggested change

After initial setup, you can choose between [automatic](##automatic-instrumentation) and [manual](##manual-instrumentation) instrumentation.

rtrieu · 2025-05-15T19:40:25Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+{{< /tabs >}}
+
+## Automatic Instrumentation
+As described in the [Setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.


Suggested change

As described in the [Setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.

As described in Step 1 of the [Android setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.

rtrieu · 2025-05-15T19:42:33Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+-   `InstrumentationMode.ANNOTATION`: Only instruments `@Composable` functions annotated with `@ComposeInstrumentation`. You can define the scope of auto-instrumentation by using this annotation.
+-   `InstrumentationMode.DISABLE`: Disables instrumentation completely.
+
+Note: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default.


Suggested change

Note: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default.

**Note**: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default.

rtrieu · 2025-05-15T19:46:34Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+{{< /tabs >}}
+
+### Setup 2 - Select the instrumentation mode
+In your module’s Gradle configuration, define the desired Compose instrumentation mode:


Suggested change

In your module’s Gradle configuration, define the desired Compose instrumentation mode:

In your module's Gradle configuration, define the desired Compose instrumentation mode:

rtrieu · 2025-05-15T19:50:14Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+{{% /tab %}}
+{{< /tabs >}}
+
+## Automatic Instrumentation


Suggested change

## Automatic Instrumentation

## Automatic Instrumentation

For full RUM coverage with minimal setup, you can automatically instrument your Jetpack Compose application.

rtrieu · 2025-05-15T20:00:07Z

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md

+As described in the [Setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.
+
+<div class="alert alert-info"><p>
+The Datadog Gradle Plugin scans @Composable functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects NavHost usage and listens to Jetpack Compose navigation events.


actually, you could do this:

Suggested change

The Datadog Gradle Plugin scans @Composable functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects NavHost usage and listens to Jetpack Compose navigation events.

The Datadog Gradle Plugin scans <code>@Composable</code> functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects <code>NavHost</code> usage and listens to Jetpack Compose navigation events.

github-actions bot added the Images Images are added/removed with this PR label May 2, 2025

ambushwork force-pushed the ylu/add-compose-instrumentation-doc branch 8 times, most recently from e3fd731 to a831dc4 Compare May 6, 2025 08:18

github-actions bot added the Architecture Everything related to the Doc backend label May 6, 2025

ambushwork force-pushed the ylu/add-compose-instrumentation-doc branch 3 times, most recently from 319bef2 to 6fe16fd Compare May 6, 2025 10:23

aleksandr-gringauz reviewed May 6, 2025

View reviewed changes

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md Outdated Show resolved Hide resolved

aleksandr-gringauz reviewed May 6, 2025

View reviewed changes

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md Outdated Show resolved Hide resolved

aleksandr-gringauz reviewed May 6, 2025

View reviewed changes

.../en/real_user_monitoring/mobile_and_tv_monitoring/android/jetpack_compose_instrumentation.md Show resolved Hide resolved

ambushwork force-pushed the ylu/add-compose-instrumentation-doc branch from 6fe16fd to 91868a1 Compare May 6, 2025 12:02

aleksandr-gringauz approved these changes May 6, 2025

View reviewed changes

ambushwork marked this pull request as ready for review May 6, 2025 15:06

ambushwork requested a review from a team as a code owner May 6, 2025 15:06

maycmlee added the editorial review Waiting on a more in-depth review label May 6, 2025

0xnm approved these changes May 6, 2025

View reviewed changes

RUM-9755: Add Jetpack Compose Instrumentation documentation

8d09a89

ambushwork force-pushed the ylu/add-compose-instrumentation-doc branch from 91868a1 to 8d09a89 Compare May 7, 2025 12:05

plousada reviewed May 7, 2025

View reviewed changes

move jetpack link to under setup

263ccf0

rtrieu requested changes May 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RUM-9755: Add Jetpack Compose Instrumentation documentation #29110

RUM-9755: Add Jetpack Compose Instrumentation documentation #29110

ambushwork commented May 2, 2025

github-actions bot commented May 2, 2025 •

edited

Loading

aleksandr-gringauz May 6, 2025

ambushwork May 6, 2025

rtrieu May 15, 2025

maycmlee commented May 6, 2025

0xnm left a comment

plousada May 7, 2025

ambushwork May 7, 2025

rtrieu left a comment

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

rtrieu May 15, 2025

	The Datadog Gradle Plugin scans @Composable functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects NavHost usage and listens to Jetpack Compose navigation events.
	The Datadog Gradle Plugin scans <code>@Composable</code> functions and adds Semantics tags to their modifiers. These tags allow Datadog RUM to track user interactions on Compose components with the correct target information. The plugin also detects <code>NavHost</code> usage and listens to Jetpack Compose navigation events.

	<div class="alert alert-info"><p>Note: The minimum supported Kotlin version is 1.9.23.</p></div>
	<div class="alert alert-info"><p>The minimum supported Kotlin version is 1.9.23.</p></div>

	If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.
	Jetpack Compose is a toolkit for building native UI in Android. If your application uses Jetpack Compose, you can instrument it manually or automatically with the Datadog Gradle Plugin. This enables Real User Monitoring (RUM) similar to what is available for Android classic Views.

	Add `dd-sdk-android-compose` dependency to each module you want to instrument. This includes the application module, any Jetpack Compose UI modules, or feature modules using Jetpack Compose.
	Add `dd-sdk-android-compose` as a dependency to each module you want to instrument. This includes the application module, any Jetpack Compose UI modules, or feature modules using Jetpack Compose.



	After initial setup, you can choose between [automatic](##automatic-instrumentation) and [manual](##manual-instrumentation) instrumentation.

	As described in the [Setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.
	As described in Step 1 of the [Android setup section][2], declare the [Datadog Gradle Plugin][3] in your build script and apply it to each module you want to instrument.

	Note: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default.
	Note: if you don't declare `composeInstrumentation` in `datadog` block, the auto-instrumentation is disabled by default.

	In your module’s Gradle configuration, define the desired Compose instrumentation mode:
	In your module's Gradle configuration, define the desired Compose instrumentation mode:

RUM-9755: Add Jetpack Compose Instrumentation documentation #29110

Are you sure you want to change the base?

RUM-9755: Add Jetpack Compose Instrumentation documentation #29110

Conversation

ambushwork commented May 2, 2025

What does this PR do? What is the motivation?

Merge instructions

Additional notes

github-actions bot commented May 2, 2025 • edited Loading

Preview links (active after the build_preview check completes)

New or renamed files

Modified Files

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maycmlee commented May 6, 2025

0xnm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rtrieu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented May 2, 2025 •

edited

Loading

Preview links (active after the `build_preview` check completes)